docs: try to clarify widget_get_state_flags vs context_get_state

diff --git a/gtk/gtkstylecontext.c b/gtk/gtkstylecontext.c
index 26b578f713dc966713a3756b683b7e8d8f79d989..dd242f139e676131c7d8002dcb59db18afcaa473 100644 (file)
--- a/gtk/gtkstylecontext.c
+++ b/gtk/gtkstylecontext.c
@@ -959,7 +959,12 @@ gtk_style_context_set_state (GtkStyleContext *context,
  * gtk_style_context_get_state:
  * @context: a #GtkStyleContext
  *
- * Returns the state used when rendering.
+ * Returns the state used when rendering. This method should
+ * only be used to retrieve the #GtkStateFlags to pass to
+ * #GtkStyleContext methods, like gtk_style_context_get_padding().
+ *
+ * If you need to retrieve the current state of a #GtkWidget you
+ * should look at gtk_widget_get_state_flags().
  *
  * Returns: the state flags
  *

diff --git a/gtk/gtkwidget.c b/gtk/gtkwidget.c
index 564f795360775693c6f5234ab08179030a2db60e..24a7249151183091703227ba3660ff78f21b4546 100644 (file)
--- a/gtk/gtkwidget.c
+++ b/gtk/gtkwidget.c
@@ -8968,6 +8968,10 @@ gtk_widget_unset_state_flags (GtkWidget     *widget,
  * returned, that is, also based on parent insensitivity, even if
  * @widget itself is sensitive.
  *
+ * Also note that if you are looking for a way to obtain the
+ * #GtkStateFlags to pass to a #GtkStyleContext method, you
+ * should look at gtk_style_context_get_state().
+ *
  * Returns: The state flags for widget
  *
  * Since: 3.0